
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Collections;
using Swaf.BizObj;
using Swaf.Container;
using Swaf.Call;

namespace Swaf.Security
{
	/// <summary>
	/// A ResourceSet is a named container holding a list of resources for which the current 
	/// principal has privileges.  The master list of resourcesets is loaded at startup via 
	/// the application feature file and is defined on the security manager class as described 
	/// earlier in this document.  ResourceSets are copied onto a new SecurityPrincipal when it 
	/// is instantiated using the ISecurityManager.createPrincipal method.
	/// 
	/// The IResourceSet interface defines the methods and properties common to all resourceset 
	/// implementations.
	/// </summary>
	public interface IResourceSet : INameAddressSupport
	{
		/// <summary>
		/// The resources property returns a reference to an INameAddressSupport container 
		/// holding the resources associated with this ResourceSet.
		/// </summary>
		INameAddressSupport resources{get;}
		
		/// <summary>
		/// The resourceCall property returns an ICall instance that points to the business 
		/// logic used to retrieve the list of resources for a specified resource set.  
		/// ResourceSets are defined in the configuration system and loaded during startup 
		/// as empty �shells.�  These ResourceSets are copied onto new SecurityPrincipal 
		/// objects instantiated by createPrincipal.  When a resource is requested from an 
		/// unpopulated ResourceSet, the resourceCall.call method is invoked to load the list 
		/// of resources.  This �lazy load� pattern is used to increase performance for 
		/// instantiation of SecurityPrincipals.
		/// </summary>
		ICall resourceCall {get;}

        /// <summary>
        /// Contains the Xml call information for the resourceCall.  This 
        /// property is helpful for recreating the resourceCall object after 
        /// serializing and deserializing a security principal or resource set.
        /// </summary>
        string resourceCallXml { get;set;}
		
		/// <summary>
		/// The isPopulated property is a simple Boolean indicator for the current state of 
		/// the resources for this ResourceSet.  If the resourceCall.call method has not been 
		/// invoked to load the list of resources, this property is false.
		/// </summary>
		bool isPopulated{get;}
		
		/// <summary>
		/// The populateResources method is used to invoke the resourceCall.call when the 
		/// isPopulated property returns false.
		/// </summary>
		void populateResources();
	    /// <summary>
	    /// Overloaded populateResources to allow additional values to be passed through.
	    /// </summary>
	    /// <param name="additionalInfo"></param>
        void populateResources(INameAddressSupport additionalInfo);
		/// <summary>
		/// The name property returns the name of this ResourceSet.  Names must be unique within 
		/// an application.  The only ResourceSet name that is currently reserved by CSF is 
		/// BizRules.  This ResourceSet is used by the RulesManager to secure the execution 
		/// of business rules.
		/// </summary>
		string name{get;}
		
		/// <summary>
		/// The clone method is invoked by the SecurityManager during the createPrincipal method 
		/// call to copy a ResourceSet so it can be added to a new SecurityPrincipal.  During 
		/// the clone process, a ResourceSet must clone each of the Resources it contains (if 
		/// present) also as they represent globally available resources.
		/// </summary>
		/// <returns></returns>
		IResourceSet clone();
		IResourceSet clone(bool deepClone);
		
		/// <summary>
		/// The populateResourcesFromList method is used to populate the resourceSet with a list 
		/// of resource definitions (INameAddressSupport object instances).  This method is 
		/// provided as a helper for application developers implementing the rule or method 
		/// for loading the associated resource objects.  Developers can simply query the database 
		/// using a DAR and return a list of business objects, then pass that list into this call 
		/// to populate the resourceset.
		/// </summary>
		/// <param name="source"></param>
		/// <returns></returns>
		INameAddressSupport populateResourcesFromList(IEnumerable source);

        /// <summary>
        /// Returns a list containing bizobj instances for each contained resource.  The 
        /// bizobj type is controlled by the resource.  If no resources exist the function
        /// should return null;
        /// </summary>
        /// <returns></returns>
	    IBizObjList getBizObjList();
	}
}
